Compendium Deluxe 2

home *** CD-ROM | disk | FTP | other *** search

/ Compendium Deluxe 2 / LSD and 17bit Compendium Deluxe - Volume II.iso / a / prog / misc / gfront11.lha / GUIFront / Developer / Doc / guifront.doc

Wrap

Text File | 1994-11-01 | 97.4 KB | 2,578 lines

TABLE OF CONTENTS guifront.library/--structures-- guifront.library/GF_CreateGUIAppA guifront.library/GF_DestroyGUIapp guifront.library/GF_CreateGUIA guifront.library/GF_DestroyGUI guifront.library/GF_GetGUIAttrA guifront.library/GF_SetGUIAttrA guifront.library/GF_GetGUIAppAttrA guifront.library/GF_SetGUIAppAttrA guifront.library/GF_GetIMsg guifront.library/GF_Wait guifront.library/GF_ReplyIMsg guifront.library/GF_SetAliasKey guifront.library/GF_BeginRefresh guifront.library/GF_EndRefresh guifront.library/GF_SetGadgetAttrsA guifront.library/GF_GetGadgetAttrsA guifront.library/GF_LockGUI guifront.library/GF_UnlockGUI guifront.library/GF_LoadPrefs guifront.library/GF_SavePrefs guifront.library/GF_LockPrefsList guifront.library/GF_UnlockPrefsList guifront.library/GF_FirstPrefsNode guifront.library/GF_NextPrefsNode guifront.library/GF_CopyAppID guifront.library/GF_GetPrefsAttrA guifront.library/GF_SetPrefsAttrA guifront.library/GF_DeletePrefs guifront.library/GF_NotifyPrefsChange guifront.library/GF_EndNotifyPrefsChange guifront.library/GF_AslRequest guifront.library/GF_EasyRequestArgs guifront.library/GF_ProcessListView guifront.library/GF_SignalPrefsVChange guifront.library/--structures-- guifront.library/--structures-- GADGETSPEC This is probably the most important structure of GUIFront. It is parsed by GF_CreateGUIA() and subsequently used to create the final gadget which will appear in your GUI. GadgetSpec structures may be reused in calls to GF_CreateGUIA(), since GUIFront does not alter any user-settable fields in the structure. Some fields will however be overwritten, as explained below. Explanation of data fields (see libraries/guifront.h as well): GadgetSpec.gs_Kind (int) The gadget "kind". All normal GadTools kinds are supported, as well as one extra kind which is used frequently in many applications: GETALT_KIND ("Get Alternative" or just "get-something") This new kind supports the following tags: GA_Disabled (BOOL) Works just like normal GadTools gadgets. ALT_Image (int) The GETALT_KIND actually breaks down into a number of different sub-kinds, as dictated by this tag: ALTI_GetDir This will give you a gadget with a "folder" image rendered inside. Typically used for directory selections. ALTI_GetFile This gives you a gadget with a "paper-with-bent-corner" image inside. Typically used for file selections. ALTI_GetMisc (default) This gives you a gadget with an "arrow-down" image inside. You can use this for selections which aren't for files or directories (names from a list, for example). ALTI_GetFont This subkind gives you a gadget with an "A" inside, suitable for Font selections. ALTI_GetScreenMode This subkind gives you a gadget with a "monitor" image usable for screen mode selections. (37.3) Note: Worked like ALTI_GetMisc under pre-37.3 versions. ALT_AslRequester (BOOL) If you supply a non-null value for this tag, GUIFront actually takes care of all the underlying ASL magic required in order to make the subkind work. For example, if the subkind is ALTI_GetFont, GUIFront automatically pops up an ASL font requester whenever the user clicks on this gadget. If the user cancels the ASL requester, your application won't even hear about it. On the other hand, if the user does select a font, you will hear an IDCMP_GADGETUP for the GETALT_KIND gadget, after which you should interrogate the ASL font requester about which font the user selected. To accomplish this you must use the ALT_AslRequester tag in a call to GF_GetGadgetAttrsA(), which in turn gives you a pointer to the actual ASL requester structure allocated by GUIFront. The selected font is then available in fo->fo_Attr.ta_Name (i.e. as normal). Note that automatic ASL requesters will lock all windows of your GUIFrontApp for the duration of the requester. Automatic requesters are supported for ALTI_GetFile, ALTI_GetFont, ALTI_GetDir and ALTI_GetScreenMode. GadgetSpec.gs_MinWidth (UWORD) If non-zero, GUIFront will set the width of the gadget hitbox to the width of this number of characters of the actual font being used. This is useful when you want to specify how many characters you want to be visible in (for example) string gadgets. GadgetSpec.gs_MinHeight (UWORD) If non-zero, GUIFront will set the height of the gadget hitbox to the height of this number of character lines of the actual font being used. This is particulary useful for specifying the minimum number of lines visible in a listview gadget, but may also be used for other resizable kinds. GadgetSpec.gs_ng (struct NewGadget) This is a fully embedded NewGadget structure. Set all fields just like you would in a normal call to GadTools' CreateGadget() funcion. Exceptions include: ng_LeftEdge ng_TopEdge ng_Width ng_Height Data in these fields will be overwritten by the position and size information of the final GadTools gadget. Do not use for private data. Note that you can examine these fields to learn the exact pixel position of the hitbox of your gadget, in case you want to do some special rendering on top of it. ng_GadgetText If the GS_Localized gs_Flags is set (see later), you would probably use this field to store the catalog string number (just a suggestion). ng_TextAttr ng_VisualInfo Data in these field will be overwritten. Do not use. GadgetSpec.gs_Tags (struct TagItem *) This field must contain the tag list to use when calling GadTools' CreateGadget function. Currently, GUIFront imposes a few restrictions on tags for certain kinds: SLIDER_KIND: All forms of level indications are not yet supported by the layout engine. This includes GTSL_MaxLevelLen, GTSL_LevelFormat, GTSL_LevelPlace and GTSL_MaxPixelLen. Using any of these tags may lead to strange looking GUIs. As a temporary workaround, simply put an invisible dummy TEXT_KIND gadget next to the slider, so GadTools will render the level indication on top of it. MX_KIND: GTMX_TitlePlace supported (even under V37), but only for PLACETEXT_ABOVE and PLACETEXT_BELOW. All other title locations are illegal. Using no title at all is of course still perfectly alright. GUIFront also changes the way certain tags are interpreted: SCROLLER_KIND: If you are using GS_DefaultTags, specify {GTSC_Arrows, 0} to _disable_ scroller arrows. Otherwise, GUIFront will append some appropriately sized arrows to your scroller gadget. LISTVIEW_KIND: For GTLV_ShowSelected, do *NOT* supply a pointer to a pre-created gadtools STRING_KIND. In stead, supply either NULL or a pointer to a STRING_KIND GadgetSpec, initialized as normal. GUIFront will do the rest. GTLV_MakeVisible is supported under V37. GadgetSpec.gs_Flags (UWORD) These flags control various aspects in relation to this particular gadget. Defined bits are: GS_NoWidthExtend GS_NoHeightExtend During layout it may be necessary for the layout engine to "stretch" members of a group. For all GadgetSpec members, this means enlarging the actual hitbox of these gadgets (buttons with PLACETEXT_IN, for example). However, this is not always desirable. For example, if you want a string gadget to show exactly 20 characters, you can do this by setting ng_MinWidth to 20 and setting GS_NoWidthExtend in gs_Flags. Note that CHECKBOX_KINDs automatically get both GS_NoWidthExtend and GS_NoHeightExtend set. Also note that GETALT_KINDs extend only vertically. GS_Localized If this flag is set, the ng_GadgetText field is ignored and the localizer function will be called to supply the gadget label. Note that GF_CreateGUIA() will fail if any of the GadgetSpecs in the layout tag list has this flag set, and you do not also supply a localizer function in your call to GF_CreateGUIA(). See GF_CreateGUIA()/GUI_LocaleFunc for more info. GS_BoldLabel Specify this flag to have the label text of this gadget rendered in bold-face (e.g. to indicate a default response). GS_DefaultTags Specify this flag to allow GUIFront to supply some reasonable default tags to your gadget. Currently, default tags include the following: All kinds: GT_Underscore, '_' CHECKBOX_KIND: GTCB_Scaled, TRUE The size of the checkbox is automatically calculated by GUIFront. MX_KIND: GTMX_Scaled, TRUE The size of the radio buttons is automatically calculated by GUIFront. GTMX_Spacing GUIFront will supply a suitable value for the distance between individual radio buttons. This currently means 4 pixels in high resolution modes and 2 otherwise. SCROLLER_KIND: GTSC_Arrows GUIFront automatically calculates how wide the scroller arrows should be based on the font being used. Note that to have SCROLLER_KINDs without arrows, either do not use GS_DefaultTags or suppy {GTSC_Arrows, 0} as a special indication telling GUIFront that you don't want the arrows. PALETTE_KIND: GTPA_IndicatorWidth, GTPA_IndicatorHeight, GUIFront calculates an appropriately sized indicator box (V37.2) and places it to the left of the palette. Under V39+ indication works by framing the selected color, and so effectively ignores these tags. Note that GS_DefaultTags always supply these tags, even if you don't want an indicator. To create a PALETTE_KIND without an indicator, simply do not use GS_DefaultTags. GTPA_Depth Your palette kind will be set to the depth of the current default public screen. GadgetSpec.gs_Gadget (struct Gadget *) (read-only) This field will be set to the value returned by GadTools' CreateGadget() function. You can use this in subsequent calls GF_Set/GetGadgetAttrsA(), and for other non-GUIFront functions which require the gadget pointer. Note: GUIFront stores a pointer to the GadgetSpec used to create a gadget in the UserData field of the gadget, so do not use this field (gadget->UserData) for private data. guifront.library/GF_CreateGUIAppA guifront.library/GF_CreateGUIAppA NAME GF_CreateGUIAppA - Create GUIFront application anchor structure (V37.2) GF_CreateGUIApp - Varargs stub for GF_CreateGUIAppA() (V37.2) SYNOPSIS guifrontapp = GF_CreateGUIAppA(appid, tags) A0 A1 GUIFrontApp *GF_CreateGUIAppA(char *, struct Tagitem *); guifrontapp = GF_CreateGUIApp(appid, ...) GUIFrontApp *GF_CreateGUIApp(char *); FUNCTION This function is used to allocate a GUIFront "anchor" structure for use in subsequent calls to functions such as GF_CreateGUIA(), and in order to give your application a symbolic name for use in the GUIFront preferences program. INPUTS appid - The symbolic name of your application. Must be less than 50 characters. Must not be an empty string (""), and NULL is NOT allowed here either. tags - Optional tags containing descriptive information about your application. Supported tags include: (The GFA prefix is short for "GUIFront Application tag") ¯ ¯ ¯ GFA_Author (char *) Author name (max 70 characters) The author of this application (probably yourself) GFA_Date (char *) Release date (max 14 characters) The date of release. The format itself is free, but it is suggested you use standard $VER: compatible date strings. GFA_LongDesc (char *) Long desciption (max 70 characters) A longer description of this application. One line only, please. GFA_Version (char *) Version information (max 20 characters) Version information pertaining to this release. The format is free. Note that GUIFront does not distinguish between two applications with the same id if they have different version numbers. Note: The above four tags are initialized by the first GUIFront application to run with this AppID, and is then effectively ignored. GFA_VisualUpdateSigBit (ULONG) Prefs change signal bit If you want to receive notification when the preferences pertaining to your application change, specify any value other than -1 here. When the preferences change, your task (or the one you specify with the GFA_VisualUpdateSigTask tag) will be signalled with the signal bit you specify here. Default is -1, no signalling. (V37.3) GFA_VisualUpdateSigTask (struct Task *) Task to update Task to signal when preferences change. This tag is valid only in connection with GFA_VisualUpdateSigBit. Default is FindTask(0). (V37.3) BUGS None known. SEE ALSO DestroyGUIApp(), CreateGUIA() guifront.library/GF_DestroyGUIApp guifront.library/GF_DestroyGUIApp NAME GF_DestroyGUIApp - Free GUIFront anchor structure (V37.2) SYNOPSIS GF_DestroyGUIApp(guifrontapp) A0 void GF_DestroyGUI(GUIFrontApp *); FUNCTION This function is used to free all resources currently in use by your application. This means closing and destroying all GUIs and deallocating the GUIFrontApp anchor structure itself. After this function returns none of your GUIs should be referenced in any way, nor should the anchor structure (it will point to garbage). INPUTS guifrontapp - As returned by GF_CreateGUIAppA() (NULL is allowed) BUGS None known. SEE ALSO GF_CreateGUIAppA() guifront.library/GF_CreateGUIA guifront.library/GF_CreateGUIA NAME GF_CreateGUIA - Create GadTools gadgets from layout tags (V37.2) GF_CreateGUI - Varargs stub for GF_CreateGUIA() (V37.2) SYNOPSIS gui = GF_CreateGUIA(guifrontapp, layout_taglist, gadgetlist, controltags) D0 A0 A1 A2 A3 GUIFront *GF_CreateGUIA(struct TagItem *, GadgetSpec **, struct TagItem *); gui = GF_CreateGUI(guifrontapp, layout_taglist, gadgetlist, ...) GUIFront *GF_CreateGUI(struct TagItem *, GadgetSpec **, ...); FUNCTION This is the main layout function of GUIFront. It accepts an array of layout tags from which it calculates not only usable gadget coordinates, but also a complete gadget context list for use directly with the WA_Gadgets tag in OpenWindowTagList(). This allows you to create fully font sensitive GUIs with a minimum of efford. This function is extremely versatile. Not only will it layout the GUI, it will also supply new-style gadget label underscoring (as seen in utilities such as Spot (Nico François), GadToolsBox (Jan van den Baard) and PowerCache (by yours truly ;-), do automatic backfilling and group framing, as well as process shift-cancellable hotkeys through a few simple GadTools replacement functions (see GF_GetIMsg() and GF_ReplyIMsg()) INPUTS guifrontapp - GUIFrontApp anchor structure to attach this GUI to (see GF_CreateGUIAppA()) gadgetlist - Pointer to NULL terminated array of pointers to all GadgetSpecs referenced in layout_list. References to GadgetSpecs not present in this list will make GF_CreateGUIA() fail. layout_taglist - Layout tag list Pointer to array of Tag Items, which fully describes the entire gadget layout. Layout tags include: (The GUIL prefix is short for "GUI Layout list") ¯¯¯ ¯ GUIL_VertGroup, (ULONG spacing) - begin a vertical group Initiates a new vertical group. The various elements in this group (GadgetSpecs or other groups) will be seperated by 'spacing' quantum units of space. Note: Make sure each GUIL_VertGroup has a matching TAG_END! GUIL_HorizGroup, (ULONG spacing) - begin a horizontal group Initiates a new horizontal group. The various elements in this group (GadgetSpecs or other groups) will be seperated by 'spacing' quantum units of space. Note: Make sure each GUIL_HorizGroup has a matching TAG_END! GUIL_GadgetSpecID, (ULONG id) - add gadget to current group Add a gadget to the current group. 'id' must match the GadgetID field of one of the GadgetSpecs supplied in 'gadgetlist'. Each GadgetSpec may be used only once in the layout tag list. GUIL_Flags, (ULONG) - miscellaneous layout control bits This flag controls various aspects of the current group. Currently, the following bits are supported: Group extension bits (all mutually exclusive): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These flags control how members in a group extend as the group itself expands, to match ajacent groups in length or height: GUILF_PropShare Members in groups which have this extension attribute maintain their relative size as the group expands: 33% 66% [ Short ] [ Very, very long ] <------- Group width -------> 33% 66% [ Short ] [ Very very long ] <------------ Group width ----------> Turn the monitor 90° and you'll have the same illustration for vertical groups. GUILF_EqualShare With this extension attribute, members are given exactly the same share of the group: 40% 60% [ Short ] [ Much longer ] <----- Group width -----> 50% 50% [ Short ] [ Much longer ] <------------- Group width -----------> Turn the monitor 90° and you'll have the same illustration for vertical groups. GUILF_EqualSize This extension attribute makes each member equally big, and then simply increases the space between members to match the size of the group: 50 pix 98 pix [ Short ] [ Much longer ] <----- Group width -----> 98 pix 98 pix [ Short ] [ Much longer ] <------------- Group width ----------> Turn the monitor 90° and you'll have the same illustration for vertical groups. Other flags (all combinations are valid): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GUILF_EqualWidth or GUILF_EqualHeight This forces all members of a group to be stretched to equal size in the secondary dimension, as illustrated in this vertical group: +----+ +--------+ | Ab | | Ab | +----+ ===\ +--------+ +--------+ ===/ +--------+ | Abcdef | | Abcdef | +--------+ +--------+ With GUILF_EqualWidth Turn the monitor 90° and you'll have the same illustration for horizontal groups. GUILF_LabelAlign This is a special alignment tag, which is only allowed in vertical groups. It causes gadgets to be vertically aligned by their hitboxes in stead of their labels: Text: [········] Text: [········] Long text: [···] Long text: [···] Normal With GUILF_LabelAlign Combining GUILF_LabelAlign and GUILF_EqualWidth gives the following rather pleasing result: Text: [········] Long text: [········] The default for GUIL_Flags is (GUILF_PropShare | GUILF_EqualHeight). Note: If you specify GUIL_Flags without specifying a group extension mode (GUIL_PropShare or GUIL_EqualShare or GUIL_EqualSize), it will default to GUIL_PropShare. (V37.3) GUIL_FrameType (ULONG frametype) GUIFront allows you to frame any group. To enable framing, specify any of the following frame types for the current group: GUILFT_Normal - A raised bevelbox (*) GUILFT_Recess - A recessed bevelbox (*) GUILFT_Ridge - Ridge frame (*) - If you are using backfilling for this GUI (see GUI_Backfill below), the interor of these frame kinds will be cleared to allow display on top of a background pattern. GUIL_FrameHeadline (char *) This tag allows you to put a "title" on a frame. It is used mostly with GUILFT_Ridge, but is also valid for other frame kinds. Note: If the current group turns out to be too short to display the entire frame headline, it will not be shown at all (truncation is ugly :-) controltags - Miscellaneous control tags Currently supported tags include: GUI_InitialOrientation (ULONG) - Initial group layout orientation This tag defines the initial layout group orientation. It must be either GUIL_VertGroup or GUIL_HorizGroup (default). Example: ULONG tags[] = { GUIL_GadgetSpecID, GID_OK, GUIL_GadgetSpecID, GID_CANCEL, GUIL_HorizGroup, 1, ... TAG_DONE }; With GUI_InitialOrientation set to GUIL_VertGroup: [ ok ] [ cancel ] (horizgroup here) With GUI_InitialOrientation set to GUIL_HorizGroup: [ ok ] [ cancel ] (horizgroup here) See also GUI_InitialSpacing below. GUI_InitialSpacing (ULONG) - Initial inter-group spacing Defines the initial group spacing of the layout tag list. The value itself is in terms of "spacing quantum units", which is something GUIFront figures out by itself. Default is 1. GUI_Backfill (BOOL) - Enable backfilling If you supply a non-null value for this tag, your window will be backfilled with the current preference backfilling pattern, as defined by the user. Backfilling typically requires that the outermost group is [recess] framed, so that gadgets and their labels are not rendered directly on top of the backfilling (which looks pretty strange :-). GUI_NewMenu (struct NewMenu *) - Attach menu Attaches a menu strip to this GUI. GUI_NewMenuLoc (struct NewMenu *) - Attach localized menu Like GUI_NewMenu, this tag is used to attach a menu strip to the GUI. However, this tag also calls your localizer function once for each item in the NewMenu array, allowing you to supply a localized menu item or title string. See GUI_LocaleFunc for information on the localizer hook, and how it is called for NewMenus. GUI_UserData (ULONG) - User data area This tag allows you to attach a custom value to each GUI. To make message handling for multi-window applications easier, you can use this area to store a pointer to a function dispatcher to call for messages pertaining to this GUI. In your main message event handling loop, you can then use the following technique to conveniently dispatch incoming IntuiMessages: ------------------------------------------------------------- GUIFront *a = GF_CreateGUI(....); GUIFront *b = GF_CreateGUI(....); GF_SetGUIAttrs(a, GUI_UserData, myfirstdispatchfunc,...); GF_SetGUIAttrs(b, GUI_UserData, myseconddispatchfunc,...); while (imsg = GF_GetIMsg(myguifrontapp)) { void (*thisdispatcher)(struct IntuiMessage *); GUIFront *thisgui; /* Pay attention here! GUIFront always stores a pointer to * the GUIFront being used for a window in the UserData * field of that window. Here's how to retrieve it: */ thisgui = imsg->IDCMPWindow->UserData; /* The only alternative method of determining which of * your GUI's `thisgui' is, is to compare it with each * of your (global) gui pointers until you get a match. * But this way is MUCH easier :-) */ GF_GetGUIAttrs(thisgui, GUI_UserData, &thisdispatcher, ..); (*thisgui)(imsg); GF_ReplyIMsg(imsg); } ------------------------------------------------------------- Note however that GUIFront does not require or expect you to use GUI_UserData in this particular way, so you are of course free to store any value you want in this field. GUI_OpenGUI (BOOL) Supply a non-null value to have GUIFront attempt to open the GUI (in a window, obviously). GUIFront works out the necessary IDCMP- and window flags. See GUI_ExtraIDCMP. GUI_WindowTitle, (char *) The desired title of the window for this GUI. GUI_ScreenTitle (char *) (V37.3) The desired title of the screen when this GUI is active. GUI_LeftEdge (short) (V37.3) The desired left edge of the GUI (once it opens). This tag is mainly used to be able to recreate and open a GUI at the same position it was at when it was closed. Default is -1, which means "center under the mouse". GUI_TopEdge (short) (V37.3) The desired top edge of the GUI (once it opens). This tag is mainly used to be able to recreate and open a GUI at the same position it was at when it was closed. Default is -1, which means "center under the mouse". GUI_ExtraIDCMP, (ULONG) GUIFront normally calculates suitable IDCMP flags for your window, but there are cases where these flags are insufficient for your application. For example, if you want notification on disk insertions, you would supply IDCMP_DISKINSERTED in GUI_ExtraIDCMP. GUI_ExtendedError (ExtErrorData *) - Extended error reporting If for some reason GF_CreateGUIA() fails, it simply returns a plain NULL. This makes tracking down layout errors rather difficult, so this tag has been provided to give you a better clue as to why the layout fails. Currently, the following error codes are returned in ExtErrorData.ee_ErrorCode: (The GFERR prefix is short for "GUIFront Error") ¯ ¯ ¯¯¯ GFERR_UNKNOWN Some unknown error occurred. GFERR_NOT_ENOUGH_MEMORY The layout engine ran out of memory. GFERR_MISSING_LOCALIZER A localized GadgetSpec was found (flags & GS_Localized), but no localizer hook was provided (see GUI_LocaleFunc). ExtErrorData.ee_ErrorData will contain a pointer to the offending GadgetSpec. GFERR_GUI_TOO_WIDE The resulting layout was too wide to open, even when falling back to topaz/8. The width, as computed by GUIFront, will be stored in ExtErrorData.ee_ErrorData for further scrutiny. GFERR_GUI_TOO_TALL The resulting layout was too tall to open, even when falling back to topaz/8. The height, as computed by GUIFront, will be stored in ExtErrorData.ee_ErrorData for further scrutiny. GFERR_CANT_FIND_SCREEN The layout engine could not locate the default public screen (which probably means your system is in big trouble at the moment) GFERR_CANT_FIND_GADGETSPECID A GadgetSpec with some GadgetID was referenced in the layout tag list, but not found in the supplied gadgetlist (see description of input parameter `gadgetlist'). The offending GadgetID will be stored in ExtErrorData.ee_ErrorData. GFERR_UNKNOWN_LAYOUT_TAG The layout tag list is incorrectly formatted, or contains garbage. Most likely you're missing a TAG_DONE somewhere. The offending tag value will be stored in ExtErrorData.ee_ErrorData. GFERR_CANT_OPEN_WINDOW This error is returned if {GUI_OpenGUI,TRUE} was specified, but the window could not be opened. The most likely cause of failure is low memory. GFERR_CANT_CREATE_MENUS GUIFront was unable to Create and Layout the NewMenu supplied by you with GUI_NewMenu. GUI_LocaleFunc ( struct Hook * ) If any of the GadgetSpec structures in the layout control taglist has its GS_Localized flag set (see --structures--), you are _required_ to supply a corresponding localizer function, or GF_CreateGUIA() will fail. The hook will be called with the following message: LocaleHookMsg (defined in include/guifront.h) { UWORD lhm_Kind : This field indicates what kind of data GUIFront wants you to localize. More precisely, it indicates which field in the embedded union is valid: LHMK_StringID means lhmd_StringID is valid LHMK_GadgetSpec means lhmd_GadgetSpec is valid LHMK_NewMenu means lhmd_NewMenu is valid union (lhm_Data) { ULONG lhmd_StringID : Return the catalog string with this id. GadgetSpec *lhmd_GadgetSpec : Return a localized string for the label of this GadgetSpec. Note: If this GadgetSpec is a CYCLE_KIND or MX_KIND, your localizer may be called several times in order to localize the individual cycle or mx items. GUIFront does this by calling your localizer once for each item to localize, with lhm_Kind == LHMK_StringID and values from the initial string array in lhmd_StringID. For example, consider the following CYCLE_KIND gadget: ------------------------------------------------- STRPTR mycyclelabels[] = { (STRPTR) CATID_MyCycItem1, (STRPTR) CATID_MyCycItem2, (STRPTR) CATID_MyCycItem3, NULL }; struct TagItem mycycletags[] = { GTCY_Labels, myccylelabels, TAG_DONE }; GadgetSpec myccyle = { CYCLE_KIND, {0,0,0,0, CATID_MyMode, NULL, GID_MYCYCLE, PLACETEXT_LEFT}, mycycletags, GS_DefaultTags | GS_Localized }; ------------------------------------------------- During the call to GF_CreateGUIA(), your localizer will be called four times for this gadget: lhm_Kind lhm_Data ----------------------------------------------------- LHMK_GadgetSpec lhmd_GadgeSpec == &mycycle LHMK_StringID lhmd_StringID == CATID_MyCycItem1 LHMK_StringID lhmd_StringID == CATID_MyCycItem2 LHMK_StringID lhmd_StringID == CATID_MyCycItem3 struct NewMenu *lhmd_NewMenu : Return a localized string for this NewMenu. You are expected to return a string with the following format: "\0Label": Menu label is "Label", no shortcut "LLabel": Menu label is "Label", shortcut is '<amiga>L' "~f1\0Label" Menu label is "Label", shortcut is 'f1'. Note that extended shortcuts are only available under V39+ } lhm_Data GUIFront will supply a pointer to the current GUIFront in the object field when calls your hook (In other words, GUIFront does a CallHookPkt(yourHook, &thisGUIFront, &localehookmsg);) RESULT Returns pointer to a GUIFront anchor structure for this GUI if everything was successfully created, or NULL on error (typically not enough memory). Use GUI_ExtendedError to obtain a more precise specification of the nature of the error which occurred. NOTES If the resulting GUI is too large to fit on the screen the routine will try topaz/8 before failing entirely. Note that this function is relatively slow. If your application is one which opens and closes its GUI several times during its lifetime, call this function only once, and then use GF_SetGUIAttrA() to open and close the GUI (see GUI_OpenGUI). EXAMPLE The following is an bare-bone example illustrating what a layout tag list looks like. Note the terminating TAG_DONE! ULONG mytags[] = { GUIL_Flags, GUILF_PropShare | GUILF_EqualWidth, GUIL_VertGroup, 1, GUIL_Flags, GUILF_EqualWidth | GUILF_PropShare, GUIL_FrameType, GUILFT_Ridge, GUIL_FrameHeadline, "User Data", GUIL_GadgetSpecID, GID_NAMESTR, GUIL_GadgetSpecID, GID_ADDRESSSTR, TAG_END, GUIL_HorizGroup, 1, GUIL_Flags, GUILF_EqualHeight | GUILF_EqualSize, GUIL_GadgetSpecID, GID_OKAY, GUIL_GadgetSpecID, GID_CANCEL, TAG_DONE, TAG_DONE /* <-- VERY important! */ } For further examples on how to use this function, please consult the example source code included in this distribution. BUGS None known (yeah, right). SEE ALSO GF_DestroyGUI() guifront.library/GF_DestroyGUI guifront.library/GF_DestroyGUI NAME GF_DestroyGUI - Free all resources obtained by GF_CreateGUIA() (V37.2) SYNOPSIS GF_DestroyGUI(guifront) A0 void GF_DestroyGUI(GUIFront *); FUNCTION This function releases all resources obtained in a successful call to GF_CreateGUIA(). This includes freeing various gadgets and BOOPSI objects. If your GUI is open when you call this function (GUI_OpenGUI == TRUE), it will be closed. INPUTS guifront - As returned by GF_CreateGUIA() (NULL is allowed) BUGS None known. SEE ALSO GF_CreateGUIA() guifront.library/GF_GetGUIAttrA guifront.library/GF_GetGUIAttrA NAME GF_GetGUIAttrA - Obtain GUI info (V37.2) GF_GetGUIAttr - Varargs stub for GF_GetGUIAttrA() (V37.2) SYNOPSIS tagsfilled = GF_GetGUIAttrA(guifront,taglist) D0 A0 A1 ULONG GF_GetGUIAttrA(GUIFront *,struct TagItem *); tagsfilled = GF_GetGUIAttr(guifront,...); ULONG GF_GetGUIAttr(GUIFront *, ...); FUNCTION Generic Get... function used to obtain information about a GUI. This is the only supported way of reading data from the GUIFront structure. Do not poke directly into the GUIFront stucture, or your application may break under a future version of the library. See TAGS for a list of supported tags. INPUTS guifront - As returned by CreateGUIA() taglist - pointer to a tag list which controls this function TAGS GUI_UserData - (ULONG *) User data Returns whatever value you poked into the UserData field in the GUIFront structure (see GF_SetGUIAttrA()). GUI_Window - (struct Window *) Pointer to GUI window Returns the current Intuition Window pointer for this GUI. If the GUI window is not currently open, NULL is returned. GUI_ActualFont - (struct TextAttr *) Copy of current TextAttr Returns a copy of the TextAttr which was actually used for the gadgets of the GUI. Useful if you need to manually Text() in some characters in the same font as the GUI is actually using. (V37.3) GUI_MenuStrip - (struct Menu *) Pointer to menu strip Returns the menu strip associated with this GUI (or NULL if no menu strip is currently attached). You can use this tag to temporarily remove the menu of GUI (ClearMenuStrip()). GUI_OpenGUI (BOOL) - Window open flag Returns TRUE if your GUI window is currently open, and FALSE otherwise. GUI_LeftEdge (short *) - Left edge of GUI window Returns the current left edge of the GUI window. You could obtain the same info by peeking in the Window structure (see GUI_Window), but this way is easier in some cases. Note that if the GUI is not currently open, this tag is ignored. (V37.3) GUI_TopEdge (short *) - Top edge of GUI window Returns the current top edge of the GUI window. You could obtain the same info by peeking in the Window structure (see GUI_Window), but this way is easier in many cases. Note that if the GUI is not currently open, this tag is ignored. (V37.3) RESULT Returns number of tag items which were actually filled. BUGS None known. SEE ALSO GF_SetGUIAttrA() guifront.library/GF_SetGUIAttrA guifront.library/GF_SetGUIAttrA NAME GF_SetGUIAttrA - Set GUI data (V37.2) GF_SetGUIAttr - Varargs stub for GF_SetGUIAttrA() (V37.2) SYNOPSIS tagsset = GF_SetGUIAttrA(guifront,taglist) D0 A0 A1 ULONG GF_SetGUIAttrA(GUIFront *,struct TagItem *); tagsset = GF_SetGUIAttr(guifront, ...) ULONG GF_SetGUIAttr(GUIFront *, ...); FUNCTION Generic Set... function used to modify GUI attributes. This is the only supported way of modifying the GUI structure. Do not poke directly into the GUIFront stucture, or your application may break under a future version of the library. See TAGS for a list of supported tags. INPUTS guifront - As returned by CreateGUIA() taglist - pointer to a tag list which controls this function TAGS GUI_UserData (ULONG) - User data You may store any value here. GUI_ExtraIDCMP (ULONG) - Extra IDCMP flags This tag can be used to temporarily change the IDCMP intuition flags for your GUI. This is useful if your application suddenly needs to listen to events such as IDCMP_DISKINSERTED. To unlisten for IDCMP_DISKINSERTED evens again, call this function with {GUI_ExtraIDCMP, 0}. GUI_OpenGUI (BOOL) - Open and close the GUI window This tag controls the state of your GUI. Specifying a nonzero value will open your GUI (if it isn't already open), and specifying a value of zero closes the GUI (if it isn't already closed). As of V37.3 a GUI will reopen at the position it was at when it was last closed (as opposed to always opening under the mouse pointer). GUI_LeftEdge (short) - left edge of GUI (V37.3) The desired left edge of the GUI. In this context this tag is used in connection with GUI_OpenGUI to explicitly position a GUI under the mouse pointer in stead of at the position at which it was last open. Specify a value of -1 to (horisontally) place the GUI under the mouse pointer. Note: This tag has no effect if the GUI is already open (not until your GUI is re-opened, anyway). GUI_TopEdge (short) - top edge of GUI (V37.3) The desired top edge of the GUI. In this context this tag is used in connection with GUI_OpenGUI to explicitly position a GUI under the mouse pointer in stead of at the position at which it was last open. Specify a value of -1 to (vertically) place the GUI under the mouse pointer. Note: This tag has no effect if the GUI is already open (not until your GUI is re-opened, anyway). RESULT Returns number of tags which were actually set. BUGS None known. SEE ALSO GF_GetGUIAttrA() guifront.library/GF_GetGUIAppAttrA guifront.library/GF_GetGUIAppAttrA NAME GF_GetGUIAppAttrA - Obtain GUI application info (V37.2) GF_GetGUIAppAttr - Varargs stub for GF_GetGUIAppAttrA() (V37.2) SYNOPSIS tagsfilled = GF_GetGUIAppAttrA(guifrontapp,taglist) D0 A0 A1 ULONG GF_GetGUIAppAttrA(GUIFrontApp *,struct TagItem *); tagsfilled = GF_GetGUIAppAttr(guifrontapp, ...) ULONG GF_GetGUIAppAttr(GUIFrontApp *, ...); FUNCTION Generic Get... function for use with the application anchor structure. This is the only supported way of reading data from the GUIFrontApp structure. Do not poke directly into the GUIFrontApp stucture, or your application may break under a future version of the library. See TAGS for a list of supported tags. INPUTS guifrontapp - As returned by CreateGUIApp() taglist - pointer to a tag list which controls this function (See TAGS below for a description of supported tags) TAGS GUIA_UserData - (ULONG *) User data Returns whatever value you poked into the UserData field of the GUIFrontApp structure (see GF_SetGUIAppAttrA()). GUIA_WindowPort - (struct MsgPort *) Window port Returns a pointer to the message port used by GUIFront to control your windows. Note that all GUIs share the same message port. Also note that reading messages directly from this port is illegal (use GF_GetIMsg() in stead). RESULT Returns number of tag items which were actually filled. BUGS None known. SEE ALSO GF_SetGUIAppAttrA(), GF_GetIMsg() guifront.library/GF_SetGUIAppAttrA guifront.library/GF_GetGUIAppAttrA NAME GF_SetGUIAppAttrA - Set application anchor data (V37.2) GF_SetGUIAppAttr - Varargs stub for GF_SetGUIAppAttrA() (V37.2) SYNOPSIS tagsset = GF_SetGUIAppAttrA(guifrontapp,taglist) D0 A0 A1 ULONG GF_SetGUIAppAttrA(GUIFrontApp *,struct TagItem *); tagsset = GF_SetGUIAppAttr(guifrontapp, ...) ULONG GF_SetGUIAppAttr(GUIFrontApp *, ...); FUNCTION Generic Set... function used to modify attributes pertaining to the application anchor structure.This is the only supported way of modifying the GUIFrontApp structure. Poking directly into the GUIFrontApp stucture may break your application under future revisions of the library. See TAGS for a list of supported tags. INPUTS guifrontapp - As returned by CreateGUIApp() taglist - pointer to a tag list which controls this function TAGS GUIA_UserData - (ULONG) User data You may store any value here. RESULT Returns number of tags which were actually set. BUGS None known. SEE ALSO GF_GetGUIAppAttrA() guifront.library/GF_GetIMsg guifront.library/GF_GetIMsg NAME GF_GetIMsg - Replacement call for GadTools' GT_GetIMsg() (V37.2) SYNOPSIS intuimessage = GF_GetIMsg(guifrontapp) D0 A0 struct IntuiMessage *GF_GetIMsg(GUIFrontApp *); FUNCTION Obtain a message from intuition and perform automatic hotkey handling of all gadgets in the associated window (GUI). This function first calls GadTools' own GT_GetIMsg. It then examines the result for possible keypresses. If it detects a keypress which matches one of the hotkeys used in this GUI, it automatically calls the appropriate gadget activation routine. It also completely handles shift-cancellable button gadgets. INPUTS guifrontapp - The GUIFront application anchor structure, as obtained with GF_CreateGUIAppA(). Note that you will be getting messages from every open GUI currently connected to this application. To find out which GUI a certain message belongs to, examine imsg->IDCMPWindow->UserData to obtain a pointer to the corresponding GUIFront structure. RESULT Returns pointer to intution message, or NULL if no more messages are available. NOTES This is a replacement call for GadTools' GT_GetIMsg(). If you want automatic hotkey processing, you must use this replacement call. On second thought, forget about using GT_GetIMsg() altogether. If you do, and if the user has selected to use simple window refreshing for your application, your windows won't be properly refreshed. BUGS None known. SEE ALSO gadtools.library/GT_GetIMsg(), exec.library/ReplyMsg() guifront.library/GF_Wait guifront.library/GF_Wait NAME GF_Wait - Replacement call for exec's Wait() (V37.2) SYNOPSIS signals = GF_Wait(guifrontapp, othersignals); A0 D0 ULONG GF_Wait(GUIFrontApp *, ULONG); FUNCTION This function waits for a message to arrive at the window port of your application, or for one of the supplied signals to become set. INPUTS guifrontapp - The GUIFront application anchor structure, as obtained with GF_CreateGUIAppA(). Note that you will be getting signals for events from every open GUI currently connected to this application. othersignals - Alternative signals to cause GF_Wait() to return RESULT Returns signals which became set (several may be set when this function returns) NOTES This function will block your application until one of the signals occur. If for some reason this never happens, your application will remain forever blocked. SEE ALSO exec.library/Wait() guifront.library/GF_ReplyIMsg guifront.library/GF_ReplyIMsg NAME GF_ReplyIMsg - Replacement call for GadTools' GT_ReplyIMsg() (V37.2) SYNOPSIS GF_ReplyIMsg(intuimsg) A0 void GF_ReplyIMsg(struct IntuiMessage *); FUNCTION Reply a modified IntuiMessage obtained with GF_GetIMsg(). If you use GF_GetIMsg(), use this function where you would normally have used exec.library/ReplyMsg(). INPUTS intuimsg - As returned by GF_GetIMsg() NOTES This is a replacement call for GadTools' GT_ReplyIMsg(). If you want automatic hotkey processing, you must use this replacement call. Only use GF_ReplyIMsg on messages returned by GF_GetIMsg(). BUGS None known. SEE ALSO gadtools.library/GT_ReplyIMsg(), exec.library/ReplyMsg() guifront.library/GF_SetAliasKey guifront.library/GF_SetAliasKey NAME GF_SetAliasKey - Define hotkey alias (V37.2) SYNOPSIS success = GF_SetAliasKey(gui, rawkey, gadgetid) A0 D0 D1 BOOL GF_SetAliasKey(GUIFront *, UBYTE, UWORD); FUNCTION This function can be used to map rawkeys to function as keyboard shortcuts for selected gadgets. Typically, you would use this function to map RETURN/ENTER to the gadget representing the "default choice" (a "Cancel" button, for example). When the user presses the alias key, your application will receive a GADGETUP message corresponding to the gadget for which the key is an alias. Alias keys for BUTTON_KINDs are also shift-cancellable, just like normal gadtools shortcut keys. INPUTS gui - As returned from GF_CreateGUIA() rawkey - Rawkey number of key to define as alias gadgetid - ID of gadget you want 'rawkey' to activate RESULTS TRUE if setting up alias key was successful, FALSE otherwise. NOTES Alias keys can be mapped to gadget which already have gadtools keyboard shortcuts (e.g. "_Use"). BUGS None known. EXAMPLE The following makes the RETURN key map a gadget with id "GID_USE": GF_SetAliasKey(myGui, 0x44, GID_USE); SEE ALSO guifront.library/GF_BeginRefresh guifront.library/GF_BeginRefresh NAME GF_BeginRefresh - Begin refreshing friendly to GUIFront (V37.2) SYNOPSIS GF_BeginRefresh(gui) A0 void GF_BeginRefresh(GUIFront *); FUNCTION Invokes the intuition.library/BeginRefresh() function in a manner friendly to both GadTools and to GUIFront. This function allows you to refresh a GUI from a generic refresh callback hook, such as the one used in connection with ASL_IntuiMsgFunc. It is not intended for use anywhere else. Call GF_EndRefresh() function when done. INPUTS gui - As returned by GF_CreateGUIA() NOTES Again, you only need this function if you are using requesters other than those supported by GUIFront (GF_AslRequest() and GF_EasyRequestArgs()), which supports callback hooks. GUIFront takes care of all normal window refreshing, including its own ASL requesters. Your hook should look something like this: struct Hook refreshhook = { {NULL, NULL}, (ULONG (*)())refreshfunc, NULL, NULL }; __saveds __asm void refreshfunc(register __a0 const struct Hook *hook, register __a2 APTR req, register __a1 struct IntuiMessage *imsg) { if (imsg->Class == IDCMP_REFRESHWINDOW) { GUIFront *gui = (GUIFront *)(imsg->IDCMPWindow->UserData); GF_BeginRefresh(gui); GF_EndRefresh(gui,TRUE); } } BUGS None known. SEE ALSO GF_EndRefresh(), gadtools.library/GT_BeginRefresh() guifront.library/GF_EndRefresh guifront.library/GF_EndRefresh NAME GF_EndRefresh - End refreshing friendly to GUIFront (V37.2) SYNOPSIS GF_EndRefresh(gui, all) A0 D0 void GF_EndRefresh(GUIFront *, BOOL); FUNCTION Invokes the intuition.library/EndRefresh() function in a manner friendly to both GadTools and to GUIFront. Call this function to end the refreshing process when you have used GF_BeginRefresh(). INPUTS gui - As returned by GF_CreateGUIA() all - TRUE when done with refreshing NOTES See GF_BeginRefresh() for an example of how to write a refresh hook. BUGS None known. SEE ALSO GF_BeginRefresh(), gadtools.library/GT_EndRefresh() guifront.library/GF_SetGadgetAttrsA guifront.library/GF_SetGadgetAttrsA NAME GF_SetGadgetAttrsA - Change attributes of a gadget (V37.2) GF_SetGadgetAttrs - Varargs stub for GF_SetGadgetAttrsA() (V37.2) SYNOPSIS GF_SetGadgetAttrsA(gui, gad, tags); A0 A1 A2 void GF_SetGadgetAttrsA(GUIFront *, struct Gadget *, struct TagItem *); GF_SetGadgetAttrs(gui, gad, ...) void GF_SetGadgetAttrs(GUIFront *, struct Gadget *, ...); FUNCTION Change the attributes of the specified gadget, according to the attributes chosen in the tag list. If an attribute is not provided in the tag list, its value remains unchanged. INPUTS gui - As returned by GF_CreateGUIA() gad - Gadget to modify tags - GadTools-compatible modification tags (note: GETALT_KIND currently does not support any modifiable tags) BUGS None known. SEE ALSO GF_GetGadgetAttrsA(), gadtools.library/GT_GetGadgetAttrsA() guifront.library/GF_GetGadgetAttrsA guifront.library/GF_GetGadgetAttrsA NAME GF_GetGadgetAttrsA - Obtain attributes of a gadget (V37.2) GF_GetGadgetAttrs - Varargs stub for GF_GetGadgetAttrsA() (V37.2) SYNOPSIS tags_gotten = GF_GetGadgetAttrsA(gui, gadget, tags) A0 A1 A2 ULONG GF_GetGadgetAttrsA(GUIFront *, struct Gadget *, struct TagItem *); tags_gotten = GF_GetGadgetAttrs(gui, gadget, ...) ULONG GF_GetGadgetAttrs(GUIFront *, struct Gadget *, ...); FUNCTION Retrieve the attributes of the specified gadget, according to the attributes chosen in the tag list. For each entry in the tag list, ti_Tag identifies the attribute, and ti_Data is a pointer to the long variable where you wish the result to be stored. INPUTS gui - As returned by GF_CreateGUIA() gadget - Gadget to obtain information about tags - GadTools compatible list of tag values to obtain. In addition to these you may also obtain information on GETALT_KINDs: ALT_AslRequester (void *) The variable pointed to by ti_Data will be set to point to the ASL requester structure allocated by GUIFront during the call to GF_CreateGUIA(). The actual type of this pointer depends on the GETALT subkind. An ALTI_GetFile or ALTI_GetDir subkind will return a pointer to a FileRequester, an ALTI_GetFont subkind will return a pointer to a FontRequester and an ALTI_GetScreenMode subkind will return a pointer to a ScreenModeRequester. RESULTS tags_gotten - The number of tags actually filled out by GUIFront. Make sure you check that this value matches what you are expecting, since unfilled tag values usually point to old data, or even to garbage. NOTES GadTools' GT_GetGadgetAttrsA() only works from V39, but the function provided here works even under V37. BUGS None known. SEE ALSO GF_GetGadgetAttrsA(), gadtools.library/GT_SetGadgetAttrsA() guifront.library/GF_LockGUI guifront.library/GF_LockGUI NAME GF_LockGUI - Lock a GUI window from user input (V37.2) SYNOPSIS GF_LockGUI(guifront) A0 void GF_LockGUI(GUIFront *); FUNCTION Lock the window of a GUI so it no longer accepts user input. The only functions left to the user are depth arrangement, window dragging and zipping. All gadgets will be un-selectable. It will also get the standard wait pointer set. The pointer at the time of locking will be restored when the window is unlocked (this will *not* happen on Kickstart V39 or higher!). Attempting to lock a GUI which is already locked will still succeed. A nesting count is maintained and incremented for each call to the function, and only when the count reaches 0 is the GUI actually unlocked. INPUTS guifront - As returned by CreateGUIA() (NULL is allowed) NOTES Each call to GF_LockGUI() must be matched by a call to GF_UnlockGUI(). BUGS None known. SEE ALSO GF_UnlockGUI(), GF_UnlockGUIApp() guifront.library/GF_UnlockGUI guifront.library/GF_UnlockGUI NAME GF_UnlockGUI - Unlock a locked GUI window (V37.2) SYNOPSIS GF_UnlockGUI(guifront) A0 void GF_UnlockGUI(GUIFront *); FUNCTION Unlock a GUI window previously locked with GF_LockGUI(). Once unlocked the window will once again accept user input and get its original mouse pointer back (default or custom). Under Kickstart V39 or higher the original window pointer will not be restored if it was set using SetWindowPointer(). You will have to restore the pointer yourself in this case. A nesting count is maintained and decremented for each call to this function, and only when the count reaches 0 is the GUI actually unlocked. INPUTS guifront - As returned by CreateGUIA() (NULL is allowed) NOTES Each call to GF_UnlockGUI() must be matched by a call to GF_LockGUI(). SEE ALSO GF_LockGUI(), GF_LockGUIApp() guifront.library/GF_LockGUIApp guifront.library/GF_LockGUIApp NAME GF_LockGUI - Lock all application GUIs from user input (V37.2) SYNOPSIS GF_LockGUIApp(guifrontapp) A0 void GF_LockGUIApp(GUIFrontApp *); FUNCTION This function provides an easy way of locking all windows associated with your application (handy for displaying blocking requesters, etc). For a more detailed explanation of just what "locking" means, refer to the description of GF_LockGUI() Attempting to lock all application GUIs when these are already locked will still succeed. A nesting count is maintained and incremented for each call to this function, and only when the count reaches 0 are the GUIs actually unlocked. INPUTS guifrontapp - As returned by CreateGUIApp() (NULL is allowed) NOTES Each call to GF_LockGUIApp() must be matched by a call to GF_UnlockGUIApp(). BUGS None known. SEE ALSO GF_UnlockGUIApp(), GF_LockGUI() guifront.library/GF_UnlockGUIApp guifront.library/GF_UnlockGUIApp NAME GF_UnlockGUI - Unlock all application GUI windows (V37.2) SYNOPSIS GF_UnlockGUIApp(guifrontapp) A0 void GF_UnlockGUIApp(GUIFrontApp *); FUNCTION Unlocks all application GUIs previously locked with GF_LockGUIApp(). Once unlocked windows will once again accept user input and get their original mouse pointers back (default or custom). See description of GF_LockGUI() for further notes on this. A nesting count is maintained and decremented for each call to this function, and only when the count reaches 0 are the GUIs actually unlocked. INPUTS guifront - As returned by CreateGUIA() (NULL is allowed) NOTES Each calls to GF_LockGUIApp() must be matched by a call to this function. SEE ALSO GF_LockGUIApp(), GF_LockGUI() guifront.library/GF_LoadPrefs guifront.library/GF_LoadPrefs NAME GF_LoadPrefs - Load preferences from a file (V37.2) SYNOPSIS success = GF_LoadPrefs(filename) A0 BOOL GF_LoadPrefs(char *); FUNCTION This function loads a set of preferences from a file into GUIFront. All previous preferences settings will be lost in the process. INPUTS filename - Name of file from which to load preferences RESULTS TRUE on success, FALSE otherwise. NOTES This function is not normally used by GUIFront programmers. BUGS None known. SEE ALSO GF_SavePrefs() guifront.library/GF_SavePrefs guifront.library/GF_SavePrefs NAME GF_SavePrefs - Save current preferences to a file SYNOPSIS GF_SavePrefs(filename) A0 void GF_SavePrefs(char *); FUNCTION This function saves the current preferences to a file (overwriting the existing file if necessary). INPUTS filename - Name of file to save preferences to NOTES This function is not normally used by GUIFront programmers. BUGS None known. EXAMPLE SEE ALSO GF_LoadPrefs() guifront.library/GF_LockPrefsList guifront.library/GF_LockPrefsList NAME GF_LockPrefsList - Lock preferences list (V37.2) SYNOPSIS GF_LockPrefsList() void GF_LockPrefsList(void); FUNCTION This function can be used to obtain an exclusive lock on GUIFront's internal application preferences list. The list should be locked prior to traversing it with GF_FirstPrefsNode() and GF_NextPrefsNode(), to prevent the list from changing midway through it. NOTES Your task will be put to sleep until the lock can be obtained. If this will never be possible, your task will never wake up. This function is not normally used by GUIFront programmers. BUGS None known. SEE ALSO GF_UnlockPrefsList(), GF_FirstPrefsNode() guifront.library/GF_UnlockPrefsList guifront.library/GF_UnlockPrefsList NAME GF_UnlockPrefsList - Unlock preferences list (V37.2) SYNOPSIS GF_UnlockPrefsList() void GF_UnlockPrefsList(void); FUNCTION This function unlocks the lock which you previously obtained with GF_LockPrefsList(). NOTES Calling this function without having obtained the lock in the first place will likely crash the system. All calls to GF_LockPrefsList() MUST be matched with a call to GF_UnlockPrefsList(). Also, don't keep a lock on the list for too long - someone else may be waiting for it. NOTES This function is not normally used by GUIFront programmers. BUGS None known. SEE ALSO GF_LockPrefsList() guifront.library/GF_FirstPrefsNode guifront.library/GF_FirstPrefsNode NAME GF_FirstPrefsNode - Find first preferences node (V37.2) SYNOPSIS handle = GF_FirstPrefsNode() PrefsHandle *GF_FirstPrefsNode(void); FUNCTION This function returns a generic handle for the first application on the preferences list. The handle itself is private, but you can use GF_CopyAppID() to obtain the name of the application using the preferences associated with the handle. This name can then be used to obtain information about the actual preferences settings for this application (via GF_GetPrefsAttrA()), or it can be used to modify them using GF_SetPrefsAttrA(). RESULTS handle - A generic preferences handle. NOTES You should make sure the preferences list is properly locked before attempting to call this function. This function is not normally used by GUIFront programmers. BUGS None known. EXAMPLE /* Scan the preferences list, printing out the ID of each * application currently being tracked by GUIFront */ PrefsHandle *ph; GF_LockPrefsList(); for (ph = GF_FirstPrefsNode; ph; ph = GF_NextPrefsNode(ph)) { char appname[50]; GF_CopyAppID(ph, appname); Printf("Application: '%s'\n", appname); } GF_UnlockPrefsList(); SEE ALSO GF_LockPrefsList(), GF_CopyAppID(), GF_NextPrefsNode() guifront.library/GF_NextPrefsNode guifront.library/GF_NextPrefsNode NAME GF_NextPrefsNode - Find next preferences node (V37.2) SYNOPSIS new_handle = GF_NextPrefsNode(prev_handle) A0 PrefsHandle *GF_NextPrefsNode(PrefsHandle *); FUNCTION Given one preferences handle, this function returns a handle on the next preferences application node in memory. It should be clear to everyone that for this to work properly, the preferences list must first be locked with GF_LockPrefsList(). INPUTS prev_handle - As returned by a previous call to GF_FirstPrefsNode() or GF_NextPrefsNode() RESULTS new_handle - A generic preferences handle (the next one in the chain) BUGS None known. NOTES This function is not normally used by GUIFront programmers. EXAMPLE See GF_FirstPrefsNode() for an example of how to do a complete scan of the preferences list. SEE ALSO GF_CopyAppID() guifront.library/GF_CopyAppID guifront.library/GF_CopyAppID NAME GF_CopyAppID - Copy application ID of preferences node (V37.2) SYNOPSIS GF_CopyAppID(prefshandle, buffer) A0 A1 void GF_CopyAppID(PrefsHandle *, char *); FUNCTION Given a private preferences handle (as returned by GF_FirstPrefsNode() or GF_NextPrefsNode()), this function copies the name of the application using those preferences to a buffer supplied by you. This is the only link between a `PrefsHandle' and GF_GetPrefsAttrA() and SetPrefsAttrA(). INPUTS prefshandle - As returned by a previous call to GF_FirstPrefsNode() or GF_NextPrefsNode() buffer - string buffer (50 chars max) to store the Application ID associated with this prefshandle (an empty string is returned for the default prefs ("", not NULL)) BUGS None known. NOTES This function is not normally used by GUIFront programmers. EXAMPLE See GF_FirstPrefsNode() for an example of using this function. SEE ALSO GF_SetPrefsAttrA(), GF_GetPrefsAttrA() guifront.library/GF_GetPrefsAttrA guifront.library/GF_GetPrefsAttrA NAME GF_GetPrefsAttrA - Obtain preferences attributes (V37.2) GF_GetPrefsAttr - Varargs stub for GF_GetPrefsAttrA() (V37.2) SYNOPSIS tags_gotten = GF_GetPrefsAttrA(appid, tags) A0 A1 int GF_GetPrefsAttrA(char *, struct TagItem *); tags_gotten = GF_GetPrefsAttr(appid, ...) int GF_GetPrefsAttr(char *, ...); FUNCTION This function is used to obtain information about individual preferences attributes for any particular application. For each item in the tag list, ti_Tag indicates the id of the attribute you wish to inquire about, and ti_Data designates a place to store the result. INPUTS appid - Application ID of prefs to ontain information about (as returned by GF_CopyAppID()). (An empty string ("") indicates the current default preferences) tags - A tag list of preferences attributes to obtain. Supported tags include the following: PRF_GadgetScreenFont (BOOL *) Your supplied BOOL will be set to TRUE if the application uses the current screen font for gadgets, and FALSE if it uses a custom font (see PRF_GadgetFontName and PRF_GadgetFontYSize) PRF_GadgetFontYSize (UWORD *) The UWORD pointed to by ti_Data will be set to the size of the custom gadget font. It is safe to ask about this tag if the application does not use a custom font. PRF_GadgetFontName (char *) The string of max 50 chars pointed to by ti_Data will be set to the name of the custom font used for gadget labels. If the application does not use a custom font, your string will be set to "\0" (i.e. an empty string). PRF_FrameScreenFont (BOOL *) The BOOL pointed to by ti_Data will be set to TRUE if the application uses the current screen font for its frame headlines, and FALSE if it uses a custom font (see PRF_FrameFontName and PRF_FrameFontYSize) PRF_FrameFontName (char *) The string of max 50 chars pointed to by ti_Data will be set to the name of the custom font used for frame headlines. If this application does not use a custom font, your string will be set to "\0" (i.e. an empty string). PRF_FrameFontYSize (UWORD *) The UWORD pointed to by ti_Data will be set to the size of the custom frame headline font. It is safe to ask about this tag if the application does not use a custom font. PRF_FrameFontBold (BOOL *) The BOOL pointed to by ti_Data will be set to TRUE if frame headlines are rendered in boldface, and FALSE otherwise. PRF_FrameFontItalics (BOOL *) The BOOL pointed to by ti_Data will be set to TRUE if frame headlines are rendered in italics, and FALSE otherwise. PRF_FrameFont3D (BOOL *) The BOOL pointed to by ti_Data will be set to TRUE if frame headlines are rendered in "3d", and FALSE otherwise. PRF_FrameFontFGPen (UWORD *) The UWORD pointed to by ti_Data will be set to the color to use for frame headlines. Note that this is the actual palette index number, not, as the name might suggest, an "intuition pen number". PRF_FrameFontCenter (BOOL *) The BOOL pointed to by ti_Data will be set to TRUE if frame headlines are being vertically centered on the frame, and FALSE if they are rendered above the frame. PRF_FrameFontCentering (UWORD *) The UWORD pointed to by ti_Data will be set to PRFFC_Left if the application is using left justified frame headlines, PRFFC_Center if it is using centered headlines and PRFFC_Right if it is using right justified headlines. PRF_AllowBackfill (BOOL *) The BOOL pointed to by ti_Data will be set to TRUE if backfilling is allowed for this application, and FALSE otherwise. PRF_BackfillFGPen (UWORD *) The UWORD pointed to by ti_Data will be set to the first color to use for window backfilling. Note that this is the actual palette index number, not, as the name might suggest, an "intuition pen number". PRF_BackfillBGPen (UWORD *) The UWORD pointed to by ti_Data will be set to the second color to use for window backfilling. Note that this is the actual palette index number, not, as the name might suggest, an "intuition pen number". PRF_FrameStyleQuery (FrameStyleQuery *) The FrameStyleQuery structure pointed to by ti_Data will be filled out according to the current rendering mode for a particular gadget. A FrameStyleQuery looks like this: typedef struct { int fsq_GadgetKind; BOOL fsq_Xen; } FrameStyleQuery; Prior to calling GF_GetPrefsAttrA(), fill out the fsq_GadgetKind field with the gadget kind you wish to acquire information about (BUTTON_KIND, for example). The fsq_Xen field will then be set to TRUE if this gadget kind is being rendered in "xen mode", and FALSE if it is being rendered in normal (GadTools) mode. PRF_XenFrameColor (UWORD *) The UWORD pointed to by ti_Data will be set to the xen framing color using by this application. PRF_SimpleRefresh (BOOL *) The BOOL pointed to by ti_Data will be set to TRUE if this application uses simple refresh windows, and FALSE if it uses smart refreshing. PRF_Author (char *) The string of max 70 characters pointed to by ti_Data will be set to the author of this application, or "" (an empty string) if this information does not exist. PRF_Date (char *) The string of max 70 characters pointed to by ti_Data will be set to the date of release of this application, or "" (an empty string) if this information does not exist. PRF_LongDesc (char *) The string of max 70 characters pointed to by ti_Data will be set to a long description of this application, or "" (an empty string) if this information does not exist. PRF_Version (char *) The string of max 70 characters pointed to by ti_Data will be set to the version of this application, or "" (an empty string) if this information does not exist. RESULTS tags_gotten - The number of tags actually filled out by GUIFront. Make sure you check that this value matches what you are expecting, since unfilled tag values usually point to old data, or even garbage. NOTES This function is not normally used by GUIFront programmers. BUGS None known. SEE ALSO GF_SetPrefsAttrA() guifront.library/GF_SetPrefsAttrA guifront.library/GF_SetPrefsAttrA NAME GF_SetPrefsAttrA - Set preferences attributes (V37.2) GF_SetPrefsAttr - Varargs stub for GF_SetPrefsAttrA() (V37.2) SYNOPSIS tags_set = GF_SetPrefsAttrA(appid, tags) A0 A1 int GF_SetPrefsAttrA(char *, struct TagItem *); tags_set = GF_SetPrefsAttr(appid, ...) int GF_SetPrefsAttr(char *, ...); FUNCTION This function is used to set individual preferences attributes for any particular application. For each item in the tag list, ti_Tag indicates the id of the attribute you wish to set, and ti_Data the new value for the attribute. Unspecified attributes remain unchanged. INPUTS appid - Application ID of prefs to change (as returned by GF_CopyAppID()) tags - A tag list of preferences attributes to change. Supported tags include the following: PRF_GadgetFontYSize (UWORD) ti_Data specifies the height of the custom font to use for Gadget labels. It is safe to supply this tag if the application does not use a custom font for gadget labels. PRF_GadgetFontName (char *) ti_Data points to a string of max 50 characters, specifying the name of the font to use for gadget labels (complete with .font extension). It is safe to use this tag if the application does not use a custom font for gadget labels. PRF_GadgetScreenFont (BOOL) If ti_Data is TRUE, the application will now use the current screen font for gadget labels. Otherwise, it will use a custom font (as previously set by PRF_GadgetFontName and PRF_GadgetFontYSize). Important note: If you set this tag to TRUE, you should also specify PRF_GadgetFontYSize and PRF_GadgetFontName, and these two tags should come PRIOR to this tag in the tag list you supply. PRF_FrameFontName (char *) ti_Data points to a string of max 50 characters, specifying the name of the font to use for frame headlines (complete with .font extension). It is safe to use this tag if the application does not use a custom font for frame headlines. PRF_FrameFontYSize (UWORD) ti_Data specifies the height of the custom font to use for frame headlines. It is safe to supply this tag if the application does not use a custom font for frame headlines. PRF_FrameScreenFont (BOOL) Set this tag to TRUE to make the application use the current screen font for frame headlines, and FALSE to use a custom font (as previously set by PRF_FrameFontName and PRF_FrameFontYSize). Important note: If you set this tag to TRUE, you should also specify PRF_FrameFontYSize and PRF_FrameFontName, and these two tags should come PRIOR to this tag in the tag list you supply. PRF_FrameFontBold (BOOL) Set this tag to TRUE to have frame headlines rendered in boldface. PRF_FrameFontItalics (BOOL) Set this tag to TRUE to have frame headlines rendered in italics. PRF_FrameFont3D (BOOL) Set this tag to TRUE to have frame headlines rendered in pseudo-3d (with a black shadow). PRF_FrameFontFGPen (UWORD) This tag is used to specify the color in which frame headlines will be rendered. Note that this is the actual palette index number, not, as the name might suggest, an "intuition pen number". PRF_FrameFontCenter (BOOL) Set this tag to TRUE to have frame headlines vertically centered on the frame, and FALSE to have them rendered above the frame. PRF_FrameFontCentering (UWORD *) Set this tag to PRFFC_Left to have frame headlines left justified on the frame, PRFFC_Center to have it centered and PRFFC_Right to have it right justified. PRF_AllowBackfill (BOOL) Set this tag to TRUE to allow this application to backfill its windows. PRF_BackfillFGPen (UWORD) This tag is used to specify the first color to use for window backfilling for this application. Note that this is the actual palette index number, not, as the name might suggest, an "intuition pen number". PRF_BackfillBGPen (UWORD) This tag is used to specify the second color to use for window backfilling for this application. Note that this is the actual palette index number, not, as the name might suggest, an "intuition pen number". PRF_FrameStyleQuery (FrameStyleQuery *) This tag is used to control frame rendering for individual gadgets. A FrameStyleQuery looks like this: typedef struct { int fsq_GadgetKind; BOOL fsq_Xen; } FrameStyleQuery; Prior to calling GF_SetPrefsAttrA(), fill out the fsq_GadgetKind field with the gadget kind for which you wish to set the frame rendering style (BUTTON_KIND, for example). Set the fsq_Xen field to TRUE if you wish this gadget kind to be rendered in "xen mode", and FALSE if you want it to be rendered in normal GadTools mode. PRF_XenFrameColor (UWORD) This tag is used to specify the color of the xen frame box which GUIFront draws around xen-gadgets. PRF_SimpleRefresh (BOOL) Set this tag to TRUE if you want this application to employ simple window refreshing (which is cheap in terms of memory usage, but tend to refresh with a bit of flicker). Set it to FALSE to use Intuition's smart refreshing scheme, which is expensive but doesn't flicker at all. NOTES This function is not normally used by GUIFront programmers. RESULTS tags_set - The number of attributes actually set. BUGS None known. SEE ALSO GF_GetPrefsAttrA() guifront.library/GF_DeletePrefs guifront.library/GF_DeletePrefs NAME GF_DeletePrefs - Delete a preferences node (V37.2) SYNOPSIS success = GF_DeletePrefs(appid) A0 BOOL GF_DeletePrefs(char *); FUNCTION This function deletes all preferences information about any particular application. When the application next starts up, it will be assigned all the default preferences. INPUTS appid - Application ID of prefs to delete (as returned by GF_CopyAppID()) RESULTS TRUE if preferences were deleted, FALSE otherwise. NOTES The preferences list need not be locked prior to calling this function. This function is not normally used by GUIFront programmers. BUGS None known. SEE ALSO guifront.library/GF_NotifyPrefsChange guifront.library/GF_NotifyPrefsChange NAME GF_NotifyPrefsChange - Set up notification on prefs changes (V37.2) SYNOPSIS success = GF_NotifyPrefsChange(task, signals) A0 D0 BOOL GF_NotifyPrefsChange(struct Task *, ULONG); FUNCTION This function asks GUIFront to signal a task when the preferences list changes. More specifically, the task will be signalled for each new application as it starts up. This allows a preferences program to keep its visual list of applications updated at all times. INPUTS task - Task you want GUIFront to signal signals - Signals you want GUIFront to send RESULTS TRUE if notification setup was successful, FALSE otherwise. NOTES You will not be notified when applications are removed from the preferences list by GF_DeletePrefs(). This function is not normally used by GUIFront programmers. BUGS None known. EXAMPLE /* This example tells GUIFront to notify the current task * with a ^F each time the preferences list changes */ GF_NotifyPrefsChange(FindTask(0), SIGBREAKF_CTRL_F); SEE ALSO GF_EndNotifyPrefsChange() guifront.library/GF_EndNotifyPrefsChange GF_EndNotifyPrefsChange NAME GF_EndNotifyPrefsChange - End preferences change notification (V37.2) SYNOPSIS GF_EndNotifyPrefsChange(task); A0 void GF_EndNotifyPrefsChange(struct Task *); FUNCTION This function terminates preferences change notification. INPUTS task - Task to end preferences change notification for, as previously set up with GF_NotifyPrefsChange() NOTES It is safe to call this function even though setting up notification with GF_NotifyPrefsChange() failed. It is imperative that the task for signalling remains running for as long as notification is active. Signalling a random memory location is not such a good idea. This function is not normally used by GUIFront programmers. BUGS None known. SEE ALSO GF_NotifyPrefsChange() guifront.library/GF_AslRequest guifront.library/GF_AslRequest NAME GF_AslRequest - Display ASL requester friendly to GUIFront (V37.2) GF_AslRequestTags - Varargs stub for GF_AslRequest() (V37.2) SYNOPSIS GF_AslRequest(requester, tags); A0 A1 BOOL GF_AslRequest(APTR, struct TagItem *); GF_AslRequestTags(requester, ...) BOOL GF_AslRequestTags(APTR, ...); FUNCTION This function puts up an ASL requester in a way which is friendly to GUIFront. This means GUIFront supplies all the proper refresh callback hooks to make the requester work with simple refreshing applications. INPUTS requester - As obtained with asl.library/AllocAslRequest() tags - As expected by asl.library/AslRequest() NOTES In order for refreshing to work, you MUST supply a pointer to one of your GUI windows, using the ASL_Window tag. Any GUI window will do, because they all share the same message port. BUGS None known. SEE ALSO asl.library/AllocAslRequest(), asl.library/AslRequest() guifront.library/GF_EasyRequestArgs guifront.library/GF_EasyRequestArgs NAME GF_EasyRequestArgs - Display EasyRequest friendly to GUIFront (V37.2) GF_EasyRequest - Varargs stub for GF_EasyRequestArgs() (V37.2) SYNOPSIS GF_EasyRequestArgs(guifrontapp, win, easystruct, idcppptr, arglist); D0 D1 A0 A1 A2 long GF_EasyRequestArgs(GUIFrontApp *,struct Window *, struct EasyStruct *,ULONG *, APTR); GF_EasyRequest(guifrontapp, win, easystruct, idcppptr, ...) long GF_EasyRequest(GUIFrontApp *,struct Window *, struct EasyStruct *,ULONG *, ...); FUNCTION This function puts up an Intuition EasyRequest in a way which is friendly to GUIFront. This means GUIFront supplies all the proper refresh callback hooks to make the requester work with simple refreshing applications. INPUTS guifrontapp - As obtained with GF_CreateGUIAppA() win - Reference window pointer, determines the screen and title of the requester window. See notes. idcmpptr - Pointer to IDCMP flags that you want to terminate the requester. This pointer may be NULL. arglist - Arguments for format commands RESULT Returns 0, 1, ..., N for successive GadgetID values, for the gadgets you specify for the requester. NOTE: The numbering from left to right is actually: 1, 2, ..., N, 0. This is for compatibility with AutoRequest(), which has FALSE for the rightmost gadget. The IDCMPFlag value is in the longword pointed to by IDCMP_ptr. -1 means that one of the caller-supplied IDCMPFlags occurred. BUGS None known. NOTE In order for refreshing to work, you MUST supply a pointer to one of your GUI windows in 'win'. Any GUI window will do, because they all share the same message port. This function will lock all GUIs of your application for the duration of the requester. Final note: If you have reqtools.library (© Nico François) installed on your system, this function will use it in stead of intuition. SEE ALSO intuition.library/EasyRequestArgs() guifront.library/GF_ProcessListView guifront.library/GF_ProcessListView NAME GF_ProcessListView - Handle listview hotkeys (V37.2) SYNOPSIS GF_ProcessListView(guifront, gadgetspec, imsg, ordinal); A0 A1 A2 A3 BOOL GF_ProcessListView(GUIFront * const, GadgetSpec * const, struct IntuiMessage * const, UWORD * const); FUNCTION This function can be used to process cursor keys as listview hotkeys. When the user presses cursor-up, the item preceeding the currently selected listview item is selected. When the user presses cursor-down, the item proceeding the currently selected listview item is selected. If the SHIFT key is held down, the currently selected item will be advanced by the number of visible listview lines, until the beginning of, or end of the listview. If the CTRL key is held down the currently selected item will be set to either the first or the last entry in the list connected to the listview. The listview will be visually correctly updated with either GTLV_MakeVisible or GTLV_Top, depending on which GadTools version the user has. INPUTS guifront - As obtained with GF_CreateGUIA() gadgetspec - Your listview GadgetSpec (NOT the gadget itself!) imsg - A message obtained with GF_GetIMsg() ordinal - The ordinal number of the new, selected item. RESULT TRUE if the user pressed a valid hotkey making the currently selected item change. FALSE if the event in 'imsg' is not a RAWKEY, or if it isn't a cursor key (in this case, ignore the result you get back in 'ordinal') BUGS None known. EXAMPLE if (imsg = GF_GetIMsg(myguifrontapp)) { switch (imsg->Class) { case IDCMP_RAWKEY: { UWORD ordinal; if (GF_ProcessListView(mygui, &mylistv, imsg, &ordinal)) { currently_selected = ordinal; update_program(); } break; } /* ... */ } /* ... */ } SEE ALSO guifront.library/GF_SignalPrefsVChange guifront.library/GF_SignalPrefsVChange NAME GF_SignalPrefsVChange - Signal prefs visual change (V37.3) SYNOPSIS GF_SignalPrefsVChange(app) A0 void GF_SignalPrefsVChange(char *); FUNCTION This function dispatches a signal to an application (or several, if they use the same appid), indicating its preferences have been edited (changed). This allows the application to recreate its GUIs using the new preferences and so always stay "in sync" with the user's current preferences. INPUTS appid - ID of application to signal NOTES This function is not normally used by GUIFront programmers. It is intended for use mainly in preference editors to send out signals to all applications when the user has changed some settings and presses the "test" button. BUGS None known.